<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>cut</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_301">&nbsp;</a>NAME</h4><blockquote>
cut - cut out selected fields of each line of a file
</blockquote><h4><a name = "tag_001_014_302">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

cut -b <i>list </i><b>[</b>-n<b>] [</b><i>file</i> ...<b>]</b>

cut -c <i>list </i><b>[</b><i>file</i> ...<b>]</b>

cut -f <i>list </i><b>[</b>-d <i>delim</i><b>][</b>-s<b>][</b><i>file</i> ...<b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_303">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>cut</i>
utility will cut out bytes
(<b>-b</b>
option), characters
(<b>-c</b>
option) or character-delimited fields
(<b>-f</b>
option) from each
line in one or more files, concatenate them and write them
to standard output.
</blockquote><h4><a name = "tag_001_014_304">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>cut</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
The option-argument
<i>list</i>
(see options
<b>-b</b>,
<b>-c</b>
and
<b>-f</b>
below) must be a comma-separated list or
blank-character-separated
list of positive numbers and ranges.
Ranges can be in three forms.
The first is two positive numbers separated by a hyphen
(<i>low-high</i>),
which represents
all fields from the first number to the second number.
The second is a positive number preceded by a hyphen
(<i>-high</i>),
which represents all fields from field number 1 to that number.
The third is a positive number followed by a hyphen
(<i>low-</i>),
which represents that number to the last field, inclusive.
The elements in list can be repeated, can overlap and can be
specified in any order.
<p>
The following options are supported:
<dl compact>

<dt><b>-b&nbsp;</b><i>list</i>
<dd>Cut based on a
<i>list</i>
of bytes.
Each selected byte will be output unless the
<b>-n</b>
option is also specified.
It is not an error to select bytes not present in the input line.

<dt><b>-c&nbsp;</b><i>list</i>
<dd>Cut based on a
<i>list</i>
of characters.
Each selected character is output.
It is not an error
to select characters not present in the input line.

<dt><b>-d&nbsp;</b><i>delim</i>
<dd>
Set the field delimiter to the character
<i>delim</i>.
The default is the
tab
character.

<dt><b>-f&nbsp;</b><i>list</i>
<dd>Cut based on a
<i>list</i>
of fields, assumed to be separated in the file by
a delimiter character (see
<b>-d</b>).
Each selected field will be output.
Output fields will be separated by
a single occurrence of the field delimiter character.
Lines with no field delimiters will be passed through intact,
unless
<b>-s</b>
is specified.
It is not an error to select fields not present in the input line.

<dt><b>-n</b>
<dd>Do not split characters.
When specified with the
<b>-b</b>
option, each element in
<i>list</i>
of the form
<i>low-high</i>
(hyphen-separated numbers)
will be modified as follows:
<ul>

<li>
If the byte selected by
<i>low</i>
is not the first byte of a character,
<i>low</i>
will be decremented to select the first byte of the character originally
selected by
<i>low</i>.
If the byte selected by
<i>high</i>
is not the last byte of
a character,
<i>high</i>
will be decremented to select the last byte of the
character prior to the character originally selected by
<i>high</i>,
or zero if there is no prior character.
If the resulting range element has
<i>high</i>
equal to zero or
<i>low</i>
greater than
<i>high</i>,
the list element will be dropped from
<i>list</i>
for that input line without causing an error.

</ul>

Each element in
<i>list</i>
of the form
<i>low-</i>
will be treated as above with
<i>high</i>
set to the number of bytes in the current line, not including the
terminating newline character.
Each element in
<i>list</i>
of the form
<i>-high</i>
will be treated as above with
<i>low</i>
set to 1.
Each element in
<i>list</i>
of the form
<i>num</i>
(a single number)
will be treated as above with
<i>low</i>
set to
<i>num</i>
and
<i>high</i>
set to
<i>num</i>.

<dt><b>-s</b>
<dd>Suppress lines with no delimiter characters, when used with the
<b>-f</b>
option.
Unless specified, lines with no delimiters will be passed
through untouched.

</dl>
</blockquote><h4><a name = "tag_001_014_305">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>file</i><dd>A pathname of an input file.
If no
<i>file</i>
operands are specified, or if a
<i>file</i>
operand is "-", the standard input will be used.

</dl>
</blockquote><h4><a name = "tag_001_014_306">&nbsp;</a>STDIN</h4><blockquote>
The standard input will be used only if no
<i>file</i>
operands are specified, or if a
<i>file</i>
operand is "-".
See the INPUT FILES section.
</blockquote><h4><a name = "tag_001_014_307">&nbsp;</a>INPUT FILES</h4><blockquote>
The input files must be text files,
except that line lengths are unlimited.
</blockquote><h4><a name = "tag_001_014_308">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>cut</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments and input files).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_309">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_310">&nbsp;</a>STDOUT</h4><blockquote>
The
<i>cut</i>
utility output will be a concatenation of the selected
bytes, characters or fields (one of the following):
<p><code>
<tt>"%s\n"</tt>, &lt;<i>concatenation of bytes</i>&gt;
<p>
<tt>"%s\n"</tt>, &lt;<i>concatenation of characters</i>&gt;
<p>
<tt>"%s\n"</tt>, &lt;<i>concatenation of fields and field delimiters</i>&gt;
</code>
</blockquote><h4><a name = "tag_001_014_311">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_312">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_313">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_314">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>All input files were output successfully.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_315">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_316">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Earlier versions of the
<i>cut</i>
utility worked in an environment where
bytes and characters were considered equivalent (modulo
backspace
and
tab character
processing in some implementations).
In the extended world of multi-byte characters, the new
<b>-b</b>
option has been added.
The
<b>-n</b>
option (used with
<b>-b</b>)
allows it to be used to
act on bytes rounded to character boundaries.
The algorithm specified for
<b>-n</b>
guarantees that:
<pre>
<code>
cut -b 1-500 -n file &gt; file1
cut -b 501- -n file &gt; file2
</code>
</pre>
will end up with all the characters in
<b>file</b>
appearing exactly once in
<b>file1</b>
or
<b>file2</b>.
(There is, however, a
newline
character in both
<b>file1</b>
and
<b>file2</b>
for each
newline
character in
<b>file</b>.)
</blockquote><h4><a name = "tag_001_014_317">&nbsp;</a>EXAMPLES</h4><blockquote>
Examples of the option qualifier list:
<dl compact>

<dt><b>1,4,7</b><dd>Select the first, fourth and seventh bytes,
characters, or fields and field delimiters.

<dt><b>1-3,8</b><dd>Equivalent to
1,2,3,8.

<dt><b>-5,10</b><dd>Equivalent to
1,2,3,4,5,10.

<dt><b>3-</b><dd>Equivalent to third to last, inclusive.

</dl>
<p>
The
<i>low-high</i>
forms are not always equivalent when used with
<b>-b</b>
and
<b>-n</b>
and multi-byte characters.
See the description of
<b>-n</b>.
<p>
The following command:
<pre>
<code>
cut -d : -f 1,6 /etc/passwd
</code>
</pre>
<p>
reads the System&nbsp;V password file (user database) and
produces lines of the form:
<pre>
<code>
&lt;user ID&gt;:&lt;home directory&gt;
</code>
</pre>
<p>
Most utilities in this specification work on text files.
The
<i>cut</i>
utility can be used to turn files with arbitrary line lengths
into a set of text files containing the same data.
The
<i><a href="paste.html">paste</a></i>
utility can be used to create (or recreate) files with arbitrary
line lengths.
For example, if
<b>file</b>
contains long lines:
<pre>
<code>
cut -b 1-500 -n file &gt; file1
cut -b 501- -n file &gt; file2
</code>
</pre>
creates
<b>file1</b>
(a text file) with lines no longer than 500 bytes
(plus the
newline
character and
<b>file2</b>
that contains the remainder of the data from
<b>file</b>.
(Note that
<b>file2</b>
will not be a
text file if there are lines in
<b>file</b>
that are longer than 500 +
{LINE_MAX}
bytes.)
The original file can be recreated from
<b>file1</b>
and
<b>file2</b>
using the command:
<pre>
<code>
paste -d "\0" file1 file2 &gt; file
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_318">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_319">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="grep.html">grep</a></i>,
<i><a href="paste.html">paste</a></i>,
<xref href=parms><a href="chap2.html#tag_001_005">
Parameters and Variables
</a></xref>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
